SignBox deployment guide for Fallback scenario.

Solution architecture

In the current document used example server address is dmee-keit-new.trustlynx.local, solution used port 9998 and all our traffic to SignBox routed through Nginx proxy (dmss-nginx) listening port 9998. During deployment replace all references to „dmee-keit-new.trustlynx.local" with server name solution is deployed.

Delivery package includes docker containers and configurations nescessary for execution. Each container configuration is located in its own folder.

Update configuration location in all locations, for docker container execution commands according to current configuraton location.

For example, if running docker in Linux server and configurations stored in /opt/docker folder replace

C:/docker/ with /opt/docker/

Execution example in this case

docker run --network signbox --name=auth -p 91:8089 -v /opt/docker/dmss-authentication-service/:/confs -e SPRING_CONFIG_LOCATION=/confs/ digitalmindss/dmss-authentication-service:1.1.7

If docker is setup as bridge network use IP addresses to access external resources (if not, use dns configuration for containers): OpenText Content Server, Outgoing email server.

Backend Services

Archive Services Fallback (dmss-archive-services-fallback)

1. Run docker container

Update documents storage volume parameter according to documents actual volume (persistent volume, shared drive/folder etc ) or configure database as documents storage. In current sample used docker hosting server folder C:/dmssdocs as document storage root mapped to fallback service container.

-v C:/dmssdocs/:/docs

docker run --network signbox --name=dmss-archive-services-fallback -p 95:8095 --restart always -v C:/docker/dmss-archive-services-fallback/:/confs -v C:/dmssdocs/:/docs -e SPRING_CONFIG_LOCATION=/confs/ digitalmindss/dmss-archive-services-fallback:1.0.18

1. Test with postman

Update postman project variables:

"fallback_service" to archive service access URL (direct URL to container published port, ex)

Execute request "FB Create Document" to create a document to archive

Execute request "FB Download file" to download a created document from archive

Archive services (dmss-archive-services)

1. Configuration updates

Update application.yml file:

Set archive connection URL to match "dmss-archive-services-fallback" service URL and port

archive-connections:

connections:

name: "FS-MAIN"

url: http://dmss-archive-services-fallback:8095/api

1. Run docker container

   docker run --network signbox --name=dmss-archive-services --restart always -p 86:8090 -v C:/docker/dmss-archive-services/:/confs -e SPRING_CONFIG_LOCATION=/confs/ digitalmindss/dmss-archive-services:2.3.27

2. Test with postman

Update postman project variables:

"archive_service" to archive service access URL (direct URL to container published port, ex )

"docid" to document ID in Content Server accessible for user defined in application.yml credentials.

Execute request "AS Download file"

Container and signature services (dmss-container-and-signature-services)

1. Configuration updates

Update application.yml file:

1. Set archive connection URL to match "dmss-archive-services" service URL and port

   dmss-archive-services:

   baseUrl: http://dmss-archive-services:8090/api

2. Set process and audit service URL to match "dmss-process-and-auditing-service" service URL and port

   dmss-process-and-auditing-service:

   baseUrl: http://dmss-process-and-auditing-service:8765;

3. Run docker container

   docker run --network signbox --name=dmss-container-and-signature-services --restart always -p 84:8092 -v C:/docker/dmss-container-and-signature-services/:/confs -e SPRING_CONFIG_LOCATION=/confs/ digii. talmindss/dmss-container-and-signature-services:1.2.13.2

4. Test with postman

Update postman project variables: "container_service" to archive service access URL and "docid" to document ID in Content Server accessible for user defined in application.yml credentials.

Execute request "AS Download file"

Default settings set for test mode. To enable TEST/PROD mode specify values in application configuration following:

ID Card

Configuration Parameter	TEST mode Value	PROD mode value
digidoc4j.configuration.mode	TEST	PROD

* In Test mode only test ID cards from SK ID solution can be used.

Smart-ID

If using Smart-ID demo mode TEST CA certificates must be added from keystore, enabling

smart.trustedCertificates: classpath:trusted_certificates.jks

Configuration Parameter	TEST mode Value	PROD mode value
smartId.hostUrl	https://sid.demo.sk.ee/smart-id-rp/v2/	https://rp-api.smart-id.com/v2
smartId.relyingPartyUUID	00000000-0000-0000-0000-000000000000	Obtained from SK ID Solutions
smartId.relyingPartyName	DEMO	Obtained from SK ID Solutions

* Smart-ID demo credentials can be found here: https://github.com/SK-EID/smart-id-documentation/wiki/Environment-technical-parameters#accounts

* More information regarding Smart-ID interactions can be found from: https://github.com/SK-EID/smart-id-documentation#3-use-case-realization-models

If a personal account must be used, download Smart-ID demo application and create a Demo Smart-ID account.

More information can be found here: https://github.com/SK-EID/smart-id-documentation/wiki/Smart-ID-demo

Mobile-ID

Configuration Parameter	TEST mode Value	PROD mode value
mobile-id.countries.EE.hostUrl	https://mid.sk.ee/mid-api	https://mid.sk.ee/mid-api
mobile-id.countries.EE.relyingPartyName	DEMO	Obtained from SK ID Solutions
mobile-id.countries.EE.relyingPartyUUID	00000000-0000-0000-0000-000000000000	Obtained from SK ID Solutions
mobile-id.countries.LT.hostUrl	https://mid.sk.ee/mid-api	https://mid.sk.ee/mid-api
mobile-id.countries.LT.relyingPartyName	DEMO	Obtained from SK ID Solutions
mobile-id.countries.LT.relyingPartyUUID	00000000-0000-0000-0000-000000000000	Obtained from SK ID Solutions

* Mobile-ID demo credentials can be found here: https://github.com/SK-EID/MID/wiki/Test-number-for-automated-testing-in-DEMO

Process and Auditing Services (dmss-process-and-auditing-service)

1. Update application.yml

2. Datasource PostgreSQL database credentials according created empty database (use database server IP address on Docker bridge mode)

   datasource:

   url: jdbc:postgresql://192.168.2.215:5432/dmss_processes

   username: dmss_processes

   password: livelink

3. Set mail server address, port and from address (use IP address in Docker bridge mode)

        mail:
        host: mail.digitalmind.lv
        port: 25
        fromAddress: "\"Keit From DMSS\" <DMSS@DMEE-KEIT-new.trustlynx.local>"

1. To send actions notifications to 3rd party application specify target URL as parameter, if baseUrl is empty or does not exist/has no callbacks sent.

   callback:

   baseUrl:

   In the specified URL, placeholders can be used to fill in by system automatically.

   Placeholers:

   {status}– status string representing action happened ('started', 'completed', 'canceled','approved', 'declined', 'signed')

   {documentid} – Document_ id related current signing process

   {processid} – Process id related current signing process

Example:

baseUrl: http://localhost/signing/status/{status}/documentid/{documentid}/process/{processid}

1. Email templates use Thymeleaf (https://www.thymeleaf.org/) framework to generate e-mail body.

If a customized email template is used, change template location resource to mapped volume folder, settings parameter value accordingly.

Example :

spring.thymeleaf.prefix: "file:/confs/templates/"

Email body transformation includes process, signer data objects and constants from application configuration.

"extportalUrl" and "intportalUrl" can be used links creation to Signbox internal or external portals.

For example access signing page.

dmss:

extportalUrl: http://signbx.company.com/extportal

intportalUrl: http://signbx.company.com/

Parameter usage example to create URLs:"

Put such value as href attribute for link "a" HTML tag ext portal url : {@{__$ {extportalUrl}__/process/$ {id}(id=$ {signer.Id})}}

Put such value as href attribute for link "a" HTML tag ext int url : {@{__$ {intportalUrl}__/process/$ {id}(id=$ {process.id})}}

„logoimg" resource reference can be used adding company branding image to e-mail body

dmss:

templates:

logoimg: classpath:logo.png

Parameter usage example to add logo into email:

    <img src="logo.png" th:src="|cid:${logo}|"></img>

1. Run docker container

   docker run --network signbox --name=dmss-process-and-auditing-service --restart always -p 88:8765 -v C:/docker/dmss-process-and-auditing-service/:/confs -e SPRING_CONFIG_LOCATION=/confs/ digitalmindss/dmss-process-and-auditing-service:1.2.12.1

Authentication Services (dmss-authentication-service)

Authentication services require internet connection to request SK ID Solutions for Smart-ID transactions. To switch authentication service from TEST to PROD mode see description in "Container and signature services" .

1. Run docker container

   docker run --network signbox --name=auth -p 91:8089 -v C:/docker/dmss-authentication-service/:/confs -e SPRING_CONFIG_LOCATION=/confs/ digitalmindss/dmss-authentication-service:1.1.7

Internal Portal

Internal Portal Keycloak

Internal portal user management using Keycloak identity management solutions more detailed installation and user manuals can be found from https://www.keycloak.org/

Create database for internal portal Keycloak. Example „dmss_intportal_keycloak".

1. Run docker container

In docker execution command Update:

a. database connection values accroring to database setup and credentials:

DB_ADDR= 192.168.2.215

DB_PORT= 5432

DB_DATABASE= dmss_intportal_keycloak

DB_USER= dmss_intportal_keycloak

DB_PASSWORD= dmss_intportal_keycloak

b. Server name and port:

HOST_NAME=http://dmee-keit-new.trustlynx.local:9998

KEYCLOAK_FRONTEND_URL=http://dmee-keit-new.trustlynx.local:9998/auth

docker run --network signbox --name=int-portal-keycloak --restart always -p 83:8080 -p 85:8088 -e HOST_NAME=http://dmee-keit-new.trustlynx.local:9998 -e keycloak_auth_url=http://dmee-keit-new.trustlynx.local:9998 -e KEYCLOAK_FRONTEND_URL=http://dmee-keit-new.trustlynx.local:9998/auth -e PROXY_ADDRESS_FORWARDING=true -e KEYCLOAK_USER=admin -e KEYCLOAK_PASSWORD=admin -e DB_VENDOR=postgres -e DB_ADDR=192.168.2.215 -e DB_PORT=5432 -e DB_DATABASE=dmss_intportal_keycloak -e DB_USER=dmss_intportal_keycloak -e DB_PASSWORD=dmss_intportal_keycloak jboss/keycloak:16.1.1

2. Keycloak setup

a. Open browser URL (replace server name accordingly): http://dmee-keit-new.trustlynx.local:83/auth/admin/

b. Login as user „admin" and password „admin"

c. Create new realm „DigitalMind"

d. Create new client „signing"

e. Set client valid redirect and web origins „*"

f. Create new role „User"

g. Create new user „test" and assign client role „User"

Internal Portal Gateway (int-portal-gateway)

Configuration updates

a. Update routed services URL according to service addresses

proxy:

servers:

Container and signature services

matchers: /api/container, /api/signing, /api/pdf, /api/stamping

server: http://dmss-container-and-signature-services:8092

Archive services

matchers: /api/document, /api/v2/document, /api/v2/auth

server: http://dmss-archive-services:8090

Process and audit services

matchers: /api/process, /api/auditing

server: http://dmss-process-and-auditing-service:8765

1. Users and groups mappings and roles. Under groupconfigurations defined list of groups enabled to use "Internal Portal". User groups tested against user assigned "Roles" in Keycloak "signing" client. User group mapping includes scope parameter with one of following values:

"USER" – members of specified group see and manage only his/her initiated process in processes list

"GROUP" – members of specified group see and manage all current group members-initiated processes in processes list

"ADMIN" – members of specified group see and manage all initiated processes of any in processes list

Example of group mapping

usersandgroups:

groupconfigurations:

groupName: User

scope: USER

jwt: asd

Run docker container

docker run --network signbox --name=int-portal-gateway --restart always -p 89:8181 -v C:/docker/int-portal-gateway/:/confs -e SPRING_CONFIG_LOCATION=/confs/ digitalmindss/proxy:1.0.12.3

Internal Portal Static (int-portal-static)

1. Configuration updates

2. Update server name in config.js file accordingly

   window.SIGNING_PATH = "http://dmee-keit-new.trustlynx.local:9998/intproxy/api/";

   window.KEYCLOAK\_CONFIG = {

   URL: "http://dmee-keit-new.trustlynx.local:9998/auth/",

3. Run docker container

   docker run --network signbox --name=int-portal-static --restart always -p 90:80 -v C:/docker/int-portal-static/locales/:/usr/share/nginx/html/public/assets/locales/ -v C:/docker/int-portal-static/nginx.conf:/etc/nginx/conf.d/default.conf -v C:/docker/int-portal-static/:/usr/share/nginx/html/config/ digitalmindss/int-portal-static:1.7.1.1

External Portal

External Portal Keycloak (ext-portal-keycloak)

Create database for internal portal Keycloak. Example „ext-portal-keycloak"

1. Configuration updates

External Portal Keycloak installation and configuration information can be found in developer portal: https://developer.signingservices.io/docs/Keycloak%20Service

1. Run docker container

In docker execution command Update:

1. Database connection values accrording to database setup and credentials:

   DB_ADDR= 192.168.2.215

   DB_PORT=5432

   DB_DATABASE= ext-portal-keycloak

   DB_USER= ext-portal-keycloak

   DB_PASSWORD= livelink

2. Replace specified frontend URL server name and cookie domain:

   KEYCLOAK_FRONTEND_URL=http:// dmee-keit-new.trustlynx.local :9998/dmsskeycloak/auth/

   COOKIE_DOMAIN= dmee-keit-new.trustlynx.local

   docker run --network signbox --name ext-portal-keycloak --restart always -p 8001:8080 -p 8008:8088 -v C:/docker/ext-portal-keycloak/messages:/opt/jboss/keycloak/themes/digitalmind/login/messages/ -v C:/docker/ext-portal-keycloak/theme.properties:/opt/jboss/keycloak/themes/digitalmind/login/theme.properties -e KEYCLOAK_FRONTEND_URL=http://dmee-keit-new.trustlynx.local:9998/dmsskeycloak/auth/ -e PROXY_CONTEXT_PATH=dmsskeycloak/auth -e KEYCLOAK_USER=admin -e KEYCLOAK_PASSWORD=admin -e DB_VENDOR=postgres -e DB_ADDR=192.168.2.215 -e DB_PORT=5432 -e DB_DATABASE=ext-portal-keycloak -e DB_USER=ext-portal-keycloak -e DB_PASSWORD=livelink -e COOKIE_DOMAIN=dmee-keit-new.trustlynx.local -e PROXY_ADDRESS_FORWARDING=true -e DM_BASE_URL="http://dmss-authentication-service:8089" digitalmindss/dmss-keycloak:1.0.8.1

External Portal Gateway (ext-portal-gateway)

1. Configuration updates

2. Update auth provider Keycloak URL and port to match „ext-portal-keycloak" URL

   auth-providers:

   name: ext-portal-keycloak

   type: OPENID

   openid-configuration: https://digitalmind.northeurope.cloudapp.azure.com/ext-portal-keycloak/auth/realms/dm-realm/.well-known/openid-configuration

3. Update routed services URL according to service addresses

proxy:

servers:

Container and signature services

matchers: /api/container, /api/signing, /api/pdf, /api/stamping

server: http://dmss-container-and-signature-services:8092

Archive services

matchers: /api/document, /api/v2/document, /api/v2/auth

server: http://dmss-archive-services:8090

Process and audit services

matchers: /api/process, /api/auditing

server: http://dmss-process-and-auditing-service:8765

Authentication services

matchers: /api/authentication

server: http://dmss-authentication-service:8089

1. Users and groups mappings must match users and groups mappings in „Internal portal gateway" configuration. Under groupconfigurations defined list of groups usersandgroups:

   groupbasedjwtheadername: X-User-Context

   groupconfigurations:

   groupName: User

   isaAdminGroup: false

   jwt: asd

2. Run docker container

   docker run --network signbox --name=ext-portal-gateway --restart always -p 92:8182 -v C:/docker/ext-portal-gateway/:/confs -e SPRING_CONFIG_LOCATION=/confs/ digitalmindss/ext-portal-gateway:1.2.4

External Portal Frontend (ext-portal-static)

1. Update configuration files a. config.js, set gateway URL accordingly:

   window.DMSS_EXTERNAL_GATEWAY = "http://dmee-keit-new.trustlynx.local:9998/extgateway/api/";

b. keycloak.js, set gateway URL accordingly:

URL: "http://dmee-keit-new.trustlynx.local:9998/dmsskeycloak/auth/",

1. Run docker container

   docker run --network signbox --name=ext-portal-static -p 9080:80 -v C:/docker/dmss-external-portal/config.js:/usr/share/nginx/html/config/config.js -v C:/docker/dmss-external-portal/keycloak.js:/usr/share/nginx/html/config/keycloak.js digitalmindss/dmss-external-portal:0.0.5.9

General Proxy (dmss-nginx)

1. Run docker container

   docker run --network signbox --name=dmss-nginx --restart always -p 9998:80 -v C:/docker/dmss-nginx/nginx.conf:/etc/nginx/nginx.conf nginx

E-mail template configuration (Thymeleaf)

1. All e-mail templates are located inside the process and audit service templates folder /opt/DMSS/dmss-process-and-auditing-service/templates/:

1. In order to edit any of the prepared e-mail templates, it is necessary to open it and adjust content using T hymeleaf rules and web development best practices. For instance, opening template email_initiator we could see such content:

You could briefly edit template with your provided text, HTML, styles and process variable replacement tags.

1. The process variable replacement tags allow to use process information into e-mail templates. For instance:

  - ${signer.signerName} - Name of a signer
  - {@__${extportalUrl}__/process/${id}(id=\\${signer.Id})} - Shared document URL
  - ${signer.signerRole} - Role of a current user
  - ${process.documentName} - The document name

1. E-mail template subject value could be defined in process service application.yml configuration file /opt/DMSS/dmss-process-and-auditing-service/application.yml:

After e-mail template was changed or application.yml file has been edited, it is important to restart the process container using the command: docker restart dmss-process-and-auditing-service

1. Logo image inside template is requested via command |cid:${logo}|. This logo is taken from the mapped path: /usr/share/nginx/html/public/assets/logo.png. Make sure this path exists and correct logo is located in this path.